home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 May: Tool Chest / Developer CD Series Tool Chest (Apple Computer)(May 1999).iso / Tool Chest / Development Kits / MPW etc / MPW-GM / MPW / Examples / CFMExamples / ModApp / Readme < prev    next >
Encoding:
Text File  |  1998-12-03  |  5.5 KB  |  112 lines  |  [TEXT/MPS ]
  1. Introduction
  2. ------------
  3. ModApp is a “modular” application from Apple’s Developer University group.
  4. It serves as a demonstration and test bed for loading external code modules
  5. into an application. ModApp can load PowerPC modules from the data fork of a
  6. file or from a resource, and can load 68K code from a resource.
  7.  
  8. (Note: The terms “tool” and “module” are used interchangeably throughout
  9. this document.)
  10.  
  11. Some of the things that ModApp demonstrates are:
  12.  
  13.     • Using CFM for conventional shared libraries (GWorldTools)
  14.     • Using CFM for custom additions (PowerPC modules)
  15.     • Calling 68K code directly
  16.     • Using MixedMode for Toolbox callbacks (Apple events support)
  17.  
  18. The code is portable between the PowerPC compilers, Symantec C++ for Power
  19. Macintosh, and Metrowerks CodeWarrior. ModApp can be built in a 68K version,
  20. a PowerPC version, or as a “fat binary” which incorporates both. (Neither
  21. Symantec C++ for Macintosh nor Metrowerks CodeWarrior currently support the
  22. CFM-68K runtime, so the 68K version must be built with MPW compilers.)
  23.  
  24. Note: The Symantec Rez compiler that is included with Symantec C++ for
  25. Power Macintosh 8.0 is not able to compile the “cfrg.r” file. The workaround
  26. is to use ToolServer and the standard MPW Rez compiler to compile “cfrg.r”
  27. and adding the resulting resource file to the project. Symantec C++ for
  28. Macintosh 7.0 (for 68K development; commonly known as THINK C) cannot be
  29. used to compile the 68K version of ModApp because it does not yet support
  30. the CFM-68K runtime model.
  31.  
  32. Building ModApp
  33. ---------------
  34. ModApp has an MPW make file to build it and all tools. The default 
  35. makefile builds “fat” versions of the application and all tools.
  36.  
  37.     • Building “all” will build a “fat” version of the app and all tools
  38.     • Building “ModApp” creates a “fat” version of the app, while 
  39.       building “ModApp.68K” makes a 68K-only version and building
  40.       “ModApp.PowerPC” creates a PowerPC-only version.
  41.     • Building “:Modules:Clock” builds only the clock module, or 
  42.       you can substitute another module name.
  43.       
  44. NOTE: The makefile requires 3 subfolders in the ModApp folder:
  45. Modules, PowerPC, and 68K. Running the “MakeFolders” script will
  46. create these for you if they don’t exist already.
  47.  
  48. If you construct your own makefile, or move this to another development
  49. system, note that the “Koch” and “Clock” modules depend on the “GWorldTools”
  50. library.
  51.  
  52. The default build has symbols turned *off* and optimization set for *size*. 
  53. Editing the “SYM” variable at the start of the makefile turns symbolic
  54. debugging on and off, editing “OPT” controls the optimization level (for PowerPC.)
  55. These options also can be set from the command line
  56.     make ModApp -d SYM=on -d OPT=off
  57. builds a debugging version. (Note that SYM=on implies OPT=off)
  58.  
  59. Theory of Operation
  60. -------------------
  61. ModApp is a fairly standard Macintosh application, though it doesn’t print or scroll.
  62. The interesting part has to do with how modules are loaded and executed. The really
  63. crucial information is contained in ToolLoader.c, ToolAPI.h, and the tool files
  64. themselves.
  65.  
  66. Since ModApp has to support both 68K and PowerPC modules, almost all calls to a module
  67. are done through Universal Procedure Pointers. When the module’s initialization routine
  68. is called, it creates a UPP for each entry point and places these in the “ToolInfoBlock”
  69. data structure. (See the ToolStartup routine in Button.c for an example of this.) ModApp
  70. then uses these UniversalProcedurePointers to call the module.
  71.  
  72. (Currently, modules do not call back to the main application, though if they did I would
  73. probably implement these callbacks using a similar table mechanism.)
  74.  
  75. The only exception to the “modules are called via Universal Procedure Pointers” rule 
  76. is the module’s “ToolStartup” routine. This routine may be called directly, or through
  77. a UniversalProcPtr -- see “InitializeTool” in ToolLoader.c for details.
  78.  
  79. The structure of a tool
  80. -----------------------
  81. A 68K module is implemented as a single 'TOOL' (0) resource, and has all of the
  82. limitations of 68K stand-alone code.
  83.  
  84. A PowerPC module may be implemented as either a PEF container in the data fork of the
  85. module’s file, or as a 'TOOL' (1) resource containing a PEF container. (NOTE: In ModApp,
  86. the PowerPC resource should not have a routine descriptor at the front, as it will be
  87. loaded and called as a native code fragment -- see LoadViaCFM in ToolLoader.c) PowerPC
  88. modules also have to contain a 'cfrg' resource to designate them as native; the type
  89. should be set to “kIsDropIn” and the location set to either kOnDiskFlat (for the data
  90. fork) or kInMem (for a resource).
  91.  
  92. “Fat” modules contain both kinds of code in the appropriate places. Don’t forget the
  93. 'cfrg' resource!
  94.  
  95. The sample modules
  96. ------------------
  97. ModApp ships with several sample modules, ranging from simple frameworks to a fancy
  98. fractal drawing demonstration:
  99.  
  100.     • Simple — a basic do-nothing module, that just draws a black rectangle in the window.
  101.     • Button - displays a single push button and beeps when the button is pressed. This
  102.       module demonstrates how a module should handle getting its own resources.
  103.     • Clock - A basic analog clock with a sweep-second hand. This demonstrates how a 
  104.       module can install and remove menus and get idle time. Clock uses the “GWorldTools”
  105.       library for off-screen drawing. (supplied)
  106.     • Koch - Draws the von Koch “snowflake” fractal over and over, rotating and colorizing
  107.       the result. This is a nice demonstration of Quickdraw’s performance.
  108.       
  109.     and finally...
  110.     
  111.     • PowerResource - A really trivial module, but one that shows how to build and load
  112.       PowerPC code resources (without going through Mixed Mode.)